gtv

type gtv

Generic Transfer Value (GTV) is a data type for the serialization and transfer of structured data, much like JSON.

GTV is used in Rell to encode operation and query arguments and results that are exchanged with clients. Unlike JSON, GTV has a stable byte serialization format and well-defined cryptographic hash, making it well-suited to this purpose. In addition, GTV supports byte arrays.

GTV supports the following types:

GTV TypeClosest Rell Equivalent
NULLnull
BYTEARRAYbyte_array
STRINGtext
INTEGERinteger
DICTmap<text, gtv>
ARRAYlist<gtv>
BIGINTEGERbig_integer

GTV does not support all Rell types, so not every value in Rell can be converted to GTV. For example, GTV has no support for non-integer numbers, and therefore the decimal type is encoded in GTV as text.

Rell types can be encoded as GTV in two modes: compact and pretty, and the distinction between the two is a real semantic difference, and is not merely a difference in whitespace when converted to text. The two modes differ in the following ways:

  • Compact GTV encode struct values as a lists of attributes, while pretty GTV encode them as a dictionaries (thus struct member names are preserved).

  • Compact GTV encode named-field tuples as a lists of attributes, while pretty GTV encode them as a dictionaries (thus tuple field names are preserved). There is no difference between the two in encoding of unnamed-field tuples.

Examples of GTV:

>>> (x = 1, y = 'a', z = true).to_gtv()
[1,"a",1]
>>> (x = 1, y = 'a', z = false).to_gtv_pretty()
{"x":1,"y":"a","z":0}
>>> [1: 'a', 2: 'b', 3: 'c'].to_gtv()
[[1,"a"],[2,"b"],[3,"c"]]
>>> [1: 'a', 2: 'b', 3: 'c'].to_gtv_pretty()
[[1,"a"],[2,"b"],[3,"c"]]
>>> set([1, 2, 3, 4]).to_gtv()
[1,2,3,4]
>>> set([1, 2, 3, 4]).to_gtv_pretty()
[1,2,3,4]
>>> struct a { x: integer; y: decimal; };
>>> a(10, 10.1).to_gtv()
[10,"10.1"]
>>> a(10, 10.1).to_gtv_pretty()
{"x":10,"y":"10.1"}

Rell operations expect their arguments as compact-encoded GTV, whereas queries expect pretty-encoded GTV arguments, hence client applications are required to use those respective formats when making operation and query calls to Rell applications.

Since

0.9.0

Functions

Link copied to clipboard
pure static function from_bytes(bytes: byte_array): gtv

Decode a GTV from a byte array.

Inverse of gtv.to_bytes().

Link copied to clipboard
pure static function from_bytes_or_null(bytes: byte_array): gtv?

Decode a GTV from a byte array.

Link copied to clipboard
pure static function from_json(json: json): gtv

Convert a JSON value to a GTV.

Inverse of gtv.to_json().

pure static function from_json(json: text): gtv

Obtain a GTV from JSON text.

First parses a JSON value from text, and then converts the JSON value to a GTV.

Equivalent to gtv.from_json(json(text)).

Link copied to clipboard
(alias) pure static function fromBytes(bytes: byte_array): gtv

Decode a GTV from a byte array.

Inverse of gtv.to_bytes().

Link copied to clipboard
(alias) pure static function fromJSON(json: json): gtv

Convert a JSON value to a GTV.

Inverse of gtv.to_json().

Alias
(alias) pure static function fromJSON(json: text): gtv

Obtain a GTV from JSON text.

First parses a JSON value from text, and then converts the JSON value to a GTV.

Equivalent to gtv.from_json(json(text)).

Alias
Link copied to clipboard
pure static function <T: -any> legacy_hash(value: T, version: integer): byte_array

Deprecated; use instead x.hash() for a value x of any type.

Link copied to clipboard
pure function to_bytes(): byte_array

Encode this GTV as byte array.

Inverse of gtv.from_bytes(byte_array).

Link copied to clipboard
pure function to_json(): json

Convert this GTV to a JSON value.

Inverse of gtv.from_json(json).

Link copied to clipboard
(alias) pure function toBytes(): byte_array

Encode this GTV as byte array.

Inverse of gtv.from_bytes(byte_array).

Alias
Link copied to clipboard
(alias) pure function toJSON(): json

Convert this GTV to a JSON value.

Inverse of gtv.from_json(json).

Alias